home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mimelib / field.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  11.3 KB  |  270 lines
  1. //=============================================================================
  2. // File:       field.h
  3. // Contents:   Declarations for DwField
  4. // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
  5. // WWW:        http://www.fwb.gulf.net/~dwsauder/mimepp.html
  6. //
  7. // Copyright (c) 1996, 1997 Douglas W. Sauder
  8. // All rights reserved.
  9. //
  10. // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
  11. // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  12. // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
  13. // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. //
  15. // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
  16. // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  17. // PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
  18. // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  19. // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. //
  21. //=============================================================================
  22.  
  23. #ifndef DW_FIELD_H
  24. #define DW_FIELD_H
  25.  
  26. #include <iostream>
  27.  
  28. #ifndef DW_CONFIG_H
  29. #include <mimelib/config.h>
  30. #endif
  31.  
  32. #ifndef DW_STRING_H
  33. #include <mimelib/string.h>
  34. #endif
  35.  
  36. #ifndef DW_MSGCMP_H
  37. #include <mimelib/msgcmp.h>
  38. #endif
  39.  
  40. class DwHeaders;
  41. class DwFieldBody;
  42.  
  43. //=============================================================================
  44. //+ Name DwField -- Class representing a MIME header field
  45. //+ Description
  46. //. {\tt DwField} represents a header field as described in RFC-822.
  47. //. According to RFC-822, a field contains a field name and a field body.
  48. //. In MIME++, a {\tt DwField} contains three elements: a {\tt DwString}
  49. //. that contains its field name, a {\tt DwString} that contains its
  50. //. field body, and a {\tt DwFieldBody} object that contains a broken-down
  51. //. (that is, parsed) version of its field body.
  52. //.
  53. //. In the tree (broken-down) representation of message, a {\tt DwField}
  54. //. object is always an intermediate node, having a parent node and a single
  55. //. child node.  The parent node is the {\tt DwHeaders} object that contains
  56. //. it.  The child node is the {\tt DwFieldBody} object it contains.
  57. //.
  58. //. To get and set the field name, use the member functions
  59. //. {\tt FieldNameStr()} and {\tt SetFieldNameStr()}.
  60. //. To get and set the field body, use the member functions
  61. //. {\tt FieldBodyStr()} and {\tt SetFieldBodyStr()}.
  62. //. To get and set the {\tt DwFieldBody} object, use {\tt FieldBody()}
  63. //. and {\tt SetFieldBody()}.
  64. //.
  65. //. A {\tt DwField} object can be included in a list of {\tt DwField}
  66. //. objects; usually this is the list of {\tt DwField} objects maintained
  67. //. by its parent {\tt DwHeaders} object.  To get the next {\tt DwField}
  68. //. object in a list, use the member function {\tt Next()}.
  69. //=============================================================================
  70. // Last updated 1997-08-23
  71. //+ Noentry ~DwField _CreateFieldBody mFieldNameStr mFieldBodyStr
  72. //+ Noentry mFieldBody _PrintDebugInfo
  73.  
  74. class DW_EXPORT DwField : public DwMessageComponent {
  75.  
  76.     friend class DwHeaders;
  77.  
  78. public:
  79.  
  80.     DwField();
  81.     DwField(const DwField& aField);
  82.     DwField(const DwString& aStr, DwMessageComponent* aParent=0);
  83.     //. The first constructor is the default constructor, which sets the
  84.     //. {\tt DwField} object's field name and field body to the empty
  85.     //. string, set its parent to {\tt NULL}, and sets its {\tt DwFieldBody}
  86.     //. object to {\tt NULL}.
  87.     //.
  88.     //. The second constructor is the copy constructor, which performs
  89.     //. a deep copy of {\tt aField}.
  90.     //. The parent of the new {\tt DwField} object is set to {\tt NULL}.
  91.     //.
  92.     //. The third constructor copies {\tt aStr} to the {\tt DwField}
  93.     //. object's string representation and sets {\tt aParent} as its parent.
  94.     //. The virtual member function {\tt Parse()} should be called immediately
  95.     //. after this constructor in order to parse the string representation.
  96.     //. Unless it is {\tt NULL}, {\tt aParent} should point to an object of
  97.     //. a class derived from {\tt DwHeaders}.
  98.  
  99.     virtual ~DwField();
  100.  
  101.     const DwField& operator = (const DwField& aField);
  102.     //. This is the assignment operator, which performs a deep copy of
  103.     //. {\tt aField}.  The parent node of the {\tt DwField} object
  104.     //. is not changed.
  105.  
  106.     virtual void Parse();
  107.     //. This virtual function, inherited from {\tt DwMessageComponent},
  108.     //. executes the parse method for {\tt DwField} objects.  The parse
  109.     //. method creates or updates the broken-down representation from the
  110.     //. string representation.  For {\tt DwField} objects, the parse method
  111.     //. parses the string representation, sets the values of the field
  112.     //. name string and the field body string, and creates an instance
  113.     //. of the appropriate subclass of {\tt DwFieldBody}.  This member
  114.     //. function also calls the {\tt Parse()} member function of its
  115.     //. contained {\tt DwFieldBody} object.
  116.     //.
  117.     //. You should call this member function after you set or modify the
  118.     //. string representation, and before you access the field name, the
  119.     //. field body, or the contained {\tt DwFieldBody} object.
  120.     //.
  121.     //. This function clears the is-modified flag.
  122.  
  123.     virtual void Assemble();
  124.     //. This virtual function, inherited from {\tt DwMessageComponent},
  125.     //. executes the assemble method for {\tt DwField} objects. The
  126.     //. assemble method creates or updates the string representation from
  127.     //. the broken-down representation.  In more concrete terms, the
  128.     //. assemble method builds the string representation from the field
  129.     //. name and the string representation of the contained {\tt DwFieldBody}
  130.     //. object.  This member function calls the {\tt Assemble()} member
  131.     //. function of its contained {\tt DwFieldBody} object.
  132.     //.
  133.     //. You should call this member function after you modify either the
  134.     //. field name or the contained {\tt DwFieldBody} object, and before
  135.     //. you retrieve the string representation.
  136.     //.
  137.     //. This function clears the is-modified flag.
  138.  
  139.     virtual DwMessageComponent* Clone() const;
  140.     //. This virtual function, inherited from {\tt DwMessageComponent},
  141.     //. creates a new {\tt DwField} on the free store that has the same
  142.     //. value as this {\tt DwField} object.  The basic idea is that of
  143.     //. a virtual copy constructor.
  144.  
  145.     DwFieldBody* FieldBody() const;
  146.     //. Returns the {\tt DwFieldBody} object contained by this {\tt DwField}
  147.     //. object.  If there is no field body, {\tt NULL} will be returned.
  148.  
  149.     const DwString& FieldNameStr() const;
  150.     //. Returns the field name of this header field as a string.
  151.  
  152.     const DwString& FieldBodyStr() const;
  153.     //. Returns the field body of this header field as a string.
  154.  
  155.     DwField* Next() const;
  156.     //. Returns the next {\tt DwField} object following this
  157.     //. {\tt DwField} object in the list contained in a {\tt DwHeaders}.
  158.     //. Returns {\tt NULL} if this object is last in the list.
  159.  
  160.     void SetFieldBody(DwFieldBody* aFieldBody);
  161.     //. Sets the {\tt DwFieldBody} object contained by this object.
  162.  
  163.     void SetFieldNameStr(const DwString& aStr);
  164.     //. Sets the field name of this header field.
  165.  
  166.     void SetFieldBodyStr(const DwString& aStr);
  167.     //. Sets the field body of this header field.
  168.  
  169.     void SetNext(const DwField* aField);
  170.     //. This {\it advanced} function sets {\tt aField} as the next field
  171.     //. following this field in the list of fields contained in the headers.
  172.     //. Since {\tt DwHeaders} contains member functions for adding
  173.     //. {\tt DwField} objects to its list, this function should be
  174.     //. avoided for most applications.
  175.  
  176.     static DwField* NewField(const DwString& aStr,
  177.         DwMessageComponent* aParent);
  178.     //. Creates a new {\tt DwField} object on the free store.
  179.     //. If the static data member {\tt sNewField} is {\tt NULL},
  180.     //. this member function will create a new {\tt DwField}
  181.     //. and return it.  Otherwise, {\tt NewField()} will call
  182.     //. the user-supplied function pointed to by {\tt sNewField},
  183.     //. which is assumed to return an object from a class derived from
  184.     //. {\tt DwField}, and return that object.
  185.  
  186.     static DwFieldBody* CreateFieldBody(const DwString& aFieldName,
  187.         const DwString& aFieldBody, DwMessageComponent* aParent);
  188.     //. The static member function {\tt CreateFieldBody()} is called from
  189.     //. the {\tt Parse()} member function and is responsible for creating a
  190.     //. {\tt DwFieldBody} object for this particular field.  A typical
  191.     //. scenario might go as follows:
  192.     //. This member function examines the field name for this field,
  193.     //. finds that it contains "To", creates a {\tt DwAddressList} object
  194.     //. to contain the field body, calls the {\tt Parse()} member
  195.     //. function for the {\tt DwAddressList}, and sets the {\tt DwAddressList}
  196.     //. object as this {\tt DwField} object's {\tt DwFieldBody}.
  197.     //.
  198.     //. If you want to override the behavior of {\tt CreateFieldBody()},
  199.     //. you can do so by setting the public data member
  200.     //. {\tt sCreateFieldBody} to point to your own function.
  201.     //. {\tt CreateFieldBody()} first checks to see if
  202.     //. {\tt sCreateFieldBody} is {\tt NULL}.  If it is not,
  203.     //. {\tt CreateFieldBody()} will assume that it points to a user-supplied
  204.     //. function and will call that function.  If it is {\tt NULL},
  205.     //. {\tt CreateFieldBody()} will call {\tt _CreateFieldBody()}, which
  206.     //. actually creates the {\tt DwFieldBody} object.  You may call
  207.     //. {\tt _CreateFieldBody()} from your own function for fields you
  208.     //. do not wish to handle.
  209.  
  210.     static DwFieldBody* _CreateFieldBody(const DwString& aFieldName,
  211.         const DwString& aFieldBody, DwMessageComponent* aParent);
  212.  
  213.     //+ Var sNewField
  214.     static DwField* (*sNewField)(const DwString&, DwMessageComponent*);
  215.     //. If {\tt sNewField} is not {\tt NULL}, it is assumed to point
  216.     //. to a user-supplied function that returns an object from a class
  217.     //. derived from {\tt DwField}.
  218.  
  219.     //+ Var sCreateFieldBody
  220.     static DwFieldBody* (*sCreateFieldBody)(const DwString& aFieldName,
  221.         const DwString& aFieldBody, DwMessageComponent* aParent);
  222.     //. See {\tt CreateFieldBody()}.
  223.  
  224. protected:
  225.  
  226.     DwString mFieldNameStr;
  227.     // the {\it field-name}
  228.  
  229.     DwString mFieldBodyStr;
  230.     // the {\it field-body}
  231.  
  232.     DwFieldBody* mFieldBody;
  233.     // pointer to the {\tt DwFieldBody} object
  234.  
  235.     void _SetFieldBody(DwFieldBody* aFieldBody);
  236.     //. Sets the {\tt DwFieldBody} object contained by this object.  This
  237.     //. function differs from {\tt SetFieldBody()} in that it does not
  238.     //. set the is-modified flag.
  239.  
  240. private:
  241.  
  242.     const DwField* mNext;
  243.     static const char* const sClassName;
  244.  
  245. public:
  246.  
  247.     virtual void PrintDebugInfo(std::ostream& aStrm, int aDepth=0) const;
  248.     //. This virtual function, inherited from {\tt DwMessageComponent},
  249.     //. prints debugging information about this object to {\tt aStrm}.
  250.     //. It will also call {\tt PrintDebugInfo()} for any of its child
  251.     //. components down to a level of {\tt aDepth}.
  252.     //.
  253.     //. This member function is available only in the debug version of
  254.     //. the library.
  255.  
  256.     virtual void CheckInvariants() const;
  257.     //. Aborts if one of the invariants of the object fails.  Use this
  258.     //. member function to track down bugs.
  259.     //.
  260.     //. This member function is available only in the debug version of
  261.     //. the library.
  262.  
  263. protected:
  264.  
  265.     void _PrintDebugInfo(std::ostream& aStrm) const;
  266.  
  267. };
  268.  
  269. #endif
  270.